<!--
    $Id: package.html 481833 2006-12-03 17:32:52Z niallp $

    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
    The ASF licenses this file to You under the Apache License, Version 2.0
    (the "License"); you may not use this file except in compliance with
    the License.  You may obtain a copy of the License at
   
         http://www.apache.org/licenses/LICENSE-2.0
   
    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
-->
<body>

<p>The "struts-logic" tag library contains tags that are useful in managing
    conditional generation of output text, looping over object collections
    for repetitive generation of output text, and application flow management.
</p>
<a name="doc.Description"></a>

<p></p>

<div align="Center"><a href="#doc.Introduction">[Introduction]</a>
    <a href="#doc.Functionality">[Logic Functionality]</a>
    <a href="#doc.Properties">[Logic Properties]</a>
    <a href="#doc.Examples">[Logic Examples]</a>
</div>

<p></p>

<hr/=""> <a name="doc.Intro"></a>

<h3>Introduction<a name="doc.Introduction"></a>
</h3>

<p> The Logic library supplies tags that are useful for manipulating
    presentation logic without the use of scriptlets.</p>

<p><br>
</p>

<div align="Center"><img src="doc-files/logicUML.gif" alt="Logic Tag UML">
    <br>
</div>

<p></p>
<a name="doc.Functionality"></a>

<h3>Logic Tag Functionality<a name="doc.Functionality"></a>
</h3>

<p> The functionality of the logic tags can be divided into four groups:</p>

<p><b>Value Comparisons -</b> The purpose of these tags is to print out the
    body of the tag if the comparison evaluates to <i>true. </i></p>

<ul>
    <li><b><a href="../../../../../../tagreference.html#equal">equal,</a>
        <a href="../../../../../../tagreference.html#notEqual">notEqual</a>
    </b></li>
    <li><b><a
            href="../../../../../../tagreference.html#greaterEqual">greaterEqual</a>
        , <a href="../../../../../../tagreference.html#lessEqual">lessEqual</a>
    </b></li>
    <li><b><a
            href="../../../../../../tagreference.html#greaterThan">greaterThan</a>
        ,<a href="../../../../../../tagreference.html#lessThan">
        lessThan</a>
    </b></li>

</ul>

<p><b>Substring Matching -</b> The purpose of these tags is to match
    substrings
    inside of other Strings</p>

<ul>
    <li><b><a
            href="../../../../../../tagreference.html#match">match</a>
        , <a href="../../../../../../tagreference.html#notMatch">notMatch</a>
    </b></li>

</ul>

<p><b>Presentation Location -</b> The purpose of these tags is to change
    the location of the presentation page</p>

<ul>
    <li><a href="../../../../../../tagreference.html#forward"><b>forward</b></a>
    </li>
    <li><a href="../../../../../../tagreference.html#redirect"><b>redirect</b></a>
    </li>

</ul>

<p><b>Collection Utilities -</b>The purpose of these tags is to handle
    Collections</p>

<ul>
    <li><a href="../../../../../../tagreference.html#iterate"><b>iterate</b></a>
    </li>

</ul>

<h3>Logic Tag Properties<a name="doc.Properties"></a>
</h3>

<p>Each of the four groups of logic tags have a common set of attributes
    associated with them. :</p>

<blockquote>
<p><b>Value Comparisons</b> (equal, notEqual, greaterEqual, lessEqual,
    greaterThan, lessThan, present, notPresent)</p>

<p>Each of the value comparison tags takes a <i>value</i> and compares
    it to the value of a comparison attribute. If the value given can be
    successfully converted to a <i>float</i> or <i>double</i>, then a number
    comparison is performed on the value given and the value of the comparison
    attribute. Otherwise a String comparison is performed. You have to specify
    one of the comparison attributes: <i>cookie</i>, <i>header</i>, <i>parameter</i>
    , <i>property</i> or <i>name. </i>For each of the examples, the tag "<i>
    someComparisonTag"</i>can be replaced by any of the value comparison
    tags.</p>

<ul>
    <li>value - the value to which this tag is going to compare, used in
        conjunction with one of the comparison attributes: <i>cookie</i>, <i>
        header</i>, <i>parameter</i>, <i>and property</i> and/or <i>name. </i>
    </li>
    <li>cookie - the name of the cookie to compare to <i>value</i>

        <ul>
            <li>example:
                <pre>&lt;logic:<i>someComparisonTag</i> value="someUserName"
                    cookie="userName"&gt;<br> User Logged In<br>&lt;/logic:<i>someComparisonTag</i>&gt;
                    <br></pre>
            </li>

        </ul>
    </li>
    <li>header - the name of the HTTP header to compare to <i>value</i>

        <ul>
            <li>example:
                <pre>&lt;logic:<i>someComparisonTag</i> value="en_US"
                    header="Accept-Language"&gt;<br> Welcome English-speaking
                    User*<br>&lt;/logic:<i>someComparisonTag</i>&gt;<br></pre>
            </li>
            <li>
                <p>*Note: See the section in the user's guide on <a
                        href="../../../../../../userGuide/building_view.html#i18n">
                    Internationalized Messages</a>
                    to do things like this better.</p>
            </li>

        </ul>
    </li>
    <li>name - the variable to be compared to <i>value</i> is the JSP bean
        specified by this attribute, if property is not specified, or the
        value
        of the specified property of this bean, if property is specified.

        <ul>
            <li>example:
                <pre>&lt;%<br> String testString = "pantalones";<br>
                    pageContext.setAttribute("testString", testString,
                    PageContext.PAGE_SCOPE);<br>%&gt;<br>&lt;jsp:useBean
                    id="testString" scope="page" type="java.lang.String" /&gt;
                    <br>&lt;logic:<i>someComparisonTag</i> name="testString"
                    value="pantalones"&gt;<br> Usted tiene pantalones!<br>&lt;/logic:<i>someComparison</i>&gt;
                    <br></pre>
            </li>

        </ul>
    </li>
    <li>parameter - the name of the request parameter to compare to
        <i>value</i>

        <ul>
            <li>example:
                <pre>&lt;logic:<i>someComparisonTag</i> value=""
                    parameter="username"&gt;<br> Error: a username must be
                    specified<br>&lt;/logic:<i>someComparisonTag</i>&gt;<br>
                </pre>
            </li>

        </ul>
    </li>
    <li>property - the variable to be compared with <i>value</i> is the
        property (of the bean specified by the name attribute) specified by
        this attribute. The property reference can be simple, nested, and/or
        indexed. <i>property</i> is used in conjunction with <i>name</i> to
        specify a property in the bean specified by <i>name</i>. For the type
        of syntax used for property, see the users guide on the Bean Tags.
    </li>
    <li>scope - the bean scope within which to search for the bean named
        by the name property, or "any scope" if not specified. Possible values
        are "page", "request", "session", "application", or "any scope"
    </li>

</ul>

<p><b>Substring Matching</b> (match, notMatch)</p>

<p>The substring matching tags take all the same arguments as the value
    comparison tags. You compare the String specified by <i>value</i> to
    any of the comparison values you give it, specified by <i>cookie</i>,
    <i>header</i>, <i>parameter</i>, <i>property</i> or <i>name.</i> Note
    that in the examples, <i>matchTag</i> corresponds either the <i>match
</i>or <i>notMatch</i> tag. Matching tags also have an additional <i>
    location</i> attribute added:</p>

<ul>
    <li>location - has two possible values, "start" and "end". If
        "start", the substring is attempted to be matched at the beginning
        of the String, if "end", then the substring is attempted to be matched
        to the end of the String
        <ul>
            <li>example:
                <pre>&lt;logic:<i>matchTag</i> parameter="action"
                    value="processLogin" location="start"&gt;<br> Processing
                    Login....<br>&lt;/logic:<i>matchTag</i>&gt;<br><br>In this
                    example, a request parameter "action" was compared to see
                    if<br>its value started with the String "processLogin". In
                    this case,<br><i>matchTag</i> would have to be &lt;logic:match&gt;.
                    <br></pre>
            </li>

        </ul>
    </li>

</ul>

<p><b>Presentation Location</b> (forward, redirect)</p>

<p>The <i>redirect</i> tag is resposible for sending a re-direct to the
    client's browser, complete with URL-rewriting if it's supported by the
    container. Its attributes are consistent with the Struts HTML <a
        href="../../../../../../userGuide/struts-html.html#link"><code>
    link</code></a>
    tag. The base URL is calculated based on which of the following attributes
    you specify (you must specify exactly one of them):</p>

<ul>
    <li> forward - Use the value of this attribute as the name of a global
        ActionForward to be looked up, and use the context-relative URI found
        there. </li>
    <li>href - Use the value of this attribute unchanged. </li>
    <li>page - Use the value of this attribute as a context-relative URI,
        and generate a server-relative URI by including the context
        path. </li>

</ul>

<p>The <i>forward</i> tag is responsible for either redirecting or forwarding
    to a specified global action forward. To define a global ActionForward,
    see The <a
        href="../../../../../../userGuide/building_controller.html#config">
    Action Mappings Configuration File</a>
    . You can specify whether the forward re-directs or forwards when executed
    in the config file. The forward tag has one attribute:</p>

<ul>
    <li>name - The logical name of the ActionForward to use</li>

</ul>

<p><b>Collection Utilities</b> (iterate)</p>

<p>The <i>iterate</i> tag is responsible for executing its body content
    once for every element inside of the specified Collection. There is one
    required attribute:</p>

<ul>
    <li>id - The name of a page scope JSP bean that will contain the current
        element of the collection on each iteration</li>

</ul>

<p>The other attributes allow for more flexibility on which Collection
    to iterate and how to do it:</p>

<ul>
    <li>collection - a runtime expression that evaluates to a Collection
        to be iterated
        <ul>
            <li>example:
                <pre>&lt;%<br> java.util.Vector vector = new
                    java.util.Vector();<br> vector.add(new Integer(12));<br>
                    vector.add(new Integer(5));<br> %&gt;<br></pre>
            </li>

        </ul>
    </li>

</ul>

<blockquote>
    <blockquote>
        <pre>&lt;logic:iterate id="myCollectionElement" collection="&lt;%=
            vector %&gt;"&gt;<br><i> Do something with myCollectionElement</i>
            &lt;/logic:iterate&gt;
        </pre>
    </blockquote>
</blockquote>

<ul>
    <li>length - The maximum number of entries (from the underlying
        collection)
        to be iterated through on this page. This can be either an integer
        that directly expresses the desired value, or the name of a JSP bean
        (in any scope) of type java.lang.Integer that defines the desired
        value.
        If not present, there will be no limit on the number of iterations
        performed</li>
    <li>name - The name of the JSP bean containing the collection to be
        iterated (if property is not specified), or the JSP bean whose
        property
        getter returns the collection to be iterated (if property is
        specified).

        <ul>
            <li>example:
                <pre>&lt;%<br>
                    java.util.ArrayList list = new java.util.ArrayList();
                    list.add("First");
                    list.add("Second");
                    list.add("Third");
                    list.add("Fourth");
                    list.add("Fifth");
                    pageContext.setAttribute("list", list,
                    PageContext.PAGE_SCOPE);
                    %&gt;

                    &lt;logic:iterate id="myCollectionElement" name="list"&gt;
                    <i>Do something with myCollectionElement</i>
                    &lt;/logic:iterate&gt;</pre>
            </li>

        </ul>
    </li>
    <li>offset - The zero-relative index of the starting point at which
        entries from the underlying collection will be iterated through. This
        can be either an integer that directly expresses the desired value,
        or the name of a JSP bean (in any scope) of type java.lang.Integer
        that defines the desired value. If not present, zero is assumed
        (meaning
        that the collection will be iterated from the beginning. </li>
    <li>property - Name of the property, of the JSP bean specified by name,
        whose getter returns the collection to be iterated. See the user's
        guide for the bean tag library for the syntax of the property
        attribute</li>
    <li>scope - The bean scope within which to search for the bean named
        by the name property, or "any scope" if not specified. Possible values
        are "page", "request", "session", "application", or "any scope"
    </li>
    <li>type - Fully qualified Java class name of the element to be exposed
        through the JSP bean named from the id attribute. If not present, no
        type conversions will be performed. NOTE: The actual elements of the
        collection must be assignment-compatible with this class, or a request
        time ClassCastException will occur.
        <ul>
            <li>example:
                <pre>&lt;% java.util.ArrayList list = new
                    java.util.ArrayList();<br>list.add("First");<br>
                    list.add("Second");<br>list.add("Third");<br>
                    list.add("Fourth");<br>list.add("Fifth");<br>
                    pageContext.setAttribute("list", list,
                    PageContext.PAGE_SCOPE);<br> %&gt;<br><br>&lt;logic:iterate
                    id="myCollectionElement" name="list"
                    type="java.lang.String"&gt;<br>  <i>Do something with
                    myCollectionElement</i>
                    &lt;/logic:iterate&gt;</pre>
            </li>

        </ul>
    </li>

</ul>
</blockquote>

<h3>Logic Examples<a name="doc.Examples"></a></h3>

<blockquote>
<p><b>Value Comparisons</b></p>

<blockquote>
<p><u></u><u></u><u>Logic Equivalence Tags (equal, notEqual,
    greaterEqual,
    lessEqual, lessThan, greaterThan)</u></p>

<blockquote>
    <p>You can compare these tags to the "==", "!=" ,"&gt;=",
        "&lt;=", "&lt;", and "&gt;"logic operators in most languages.
        Their usage is fairly straightforward for numbers. For an
        example,
        we'll create a small "Guess That Number" game that uses
        request parameters
        from a form input to play. The number will be hardcoded as
        "7", because
        this is just an example. Note that this is actually putting
        application
        logic inside of jsp pages, and isn't the recommended
        development
        method for Struts. It's just an easy way to show how these
        tags are
        used:</p>

    <p>The first step is to develop the form that will call on the
        processing jsp page. This form will use the "GET" method so
        that
        you can see the request parameter in the URL. The POST method
        can
        also be used with no problem or changes.</p>

    <p>[numberGuess.jsp]</p>

    <pre>&lt;form action="numberProcess.jsp" method="GET"&gt;<br>
        Please Enter a Number From 1-10: &lt;input type="text"
        name="number" /&gt;&lt;br /&gt;<br> &lt;center&gt;<br> &lt;input
        type="submit" name="Guess Number" /&gt;<br> &lt;/center&gt;
        <br>&lt;/form&gt;<br></pre>
    The next step is to create the processing page. It uses the
    struts-logic
    taglib. For information on how to set this tag library up in your
    application
    to use, see <a
        href="../../../../../../userGuide/configuration.html#dd_config">
    The Web Application Deployment Descriptor</a>

    <p>[numberProcess.jsp]</p>

    <pre>&lt;%@ page language="java" %&gt;<br>&lt;%@ taglib
        uri="/WEB-INF/struts-logic.tld" prefix="logic" %&gt;<br></pre>

    <pre>&lt;!-- Is the number guess right? --&gt;<br>&lt;logic:equal
        parameter="number" value="7"&gt;<br> You guessed right! You
        win a high speed blender!<br>&lt;/logic:equal&gt;<br></pre>

    <pre>&lt;!-- If the number guessed was wrong --&gt;<br>&lt;logic:notEqual
        parameter="number" value="7"&gt;<br> &lt;!-- Less Than --&gt;
        <br> &lt;logic:lessThan parameter="number" value="7"&gt;<br> A
        little higher...<br> &lt;/logic:lessThan&gt;<br> &lt;!--
        Greater Than --&gt;<br> &lt;logic:greaterThan
        parameter="number" value="7"&gt;<br> A little lower...<br>
        &lt;/logic:greaterThan&gt;<br>&lt;/logic:notEqual&gt;<br>
    </pre>

    <p>Basically, the numberProcess.jsp page uses the equal tag to
        check if the guess is 7, and if so, prints out a
        congratulatory message.
        If the number isn't equal, specified by the use of the &lt;logic:notEqual&gt;
        tag, it uses the greaterThan and lessThan tags to check if the
        number
        is higher or lower than 7, and prints out a hint. As said
        before,
        this is a horribly designed small application, with no
        validity checks
        on the number input, but shows the basic usage of the logic
        equal
        tags</p>

    <p>For String comparisons, the equal tags use the
        java.lang.String.compareTo()
        method. See the javadocs on the compareTo() method for more
        information,
        located <a
            href="http://www.javasoft.com/products/jdk/1.2/docs/api/java/lang/String.html#compareTo%28java.lang.Object%29">
        here</a>
        .</p>
</blockquote>

<p><u>Match and Present Tags (match, notMatch, present,
    notPresent)</u></p>

<blockquote>
    <p>You use the match tags in conjunction with the present tags
        in order to do substring matches. For an example using this
        we'll
        use headers, specifically the "Referer" header. The HTTP
        referer
        header gives the URL of the document that refers to the
        requested
        URL. We'll use this to check if the user is coming from a link
        specified
        by a <a href="http://www.google.com">Google</a>
        search, and offer a personalized greeting, frightening users
        that
        find our site through the search engine with our amazing
        intimate
        knowledge of their browsing habits:</p>

    <p>[sneaky.jsp]</p>

    <pre>&lt;%@ page language="java" %&gt;<br>&lt;%@ taglib
        uri="/WEB-INF/struts-logic.tld" prefix="logic" %&gt;<br><br>
        <br>&lt;!-- Check to see if the "Referer" header is present --&gt;
        <br>&lt;logic:present header="Referer"&gt;<br> &lt;logic:match
        header="Referer" value="google.com"&gt;<br> I see you found
        our site through Google... interesting.<br> &lt;/logic:match&gt;
        <br> &lt;logic:notMatch header="Referer" value="google.com"&gt;
        <br> Welcome to the site, we're secretly logging what site you
        came from,<br> because we're shady...<br> &lt;/logic:notMatch&gt;
        <br>&lt;/logic:present&gt;<br><br>&lt;!-- If the header is not
        present --&gt;<br>&lt;logic:notPresent header="Referer"&gt;
        <br> Hi, welcome to our site. Please fill out our<br> &lt;a
        href="nonExistantForm.jsp"&gt;Form&lt;/a&gt; and<br> tell us
        where you're coming from.<br>&lt;/logic:notPresent&gt;</pre>

    <p>Note: Another interesting usage of these tags and headers
        would be to use the "User-Agent" header to display
        browser-specific
        javascript.</p>
</blockquote>
</blockquote>

<p><b>Collection Utilities (iterate)</b></p>

<blockquote>
    <p>For an example of using the &lt;logic:iterate&gt; tag,
        we'll use one of the previous examples given, in it's entirety.
        This
        example uses the &lt;bean:write&gt; tag from the Bean Tag Library,
        see the User's Guide on the bean tag library for more information
        on
        it's usage:</p>

    <p>[iterate.jsp]</p>

    <pre>&lt;%@ page language="java" %&gt;<br>&lt;%@ taglib
        uri="/WEB-INF/struts-bean.tld" prefix="bean" %&gt;<br>&lt;%@
        taglib uri="/WEB-INF/struts-logic.tld" prefix="logic" %&gt;<br>
    </pre>

    <pre>&lt;%<br>java.util.ArrayList list = new java.util.ArrayList();
        <br> list.add("First");<br> list.add("Second");<br>
        list.add("Third");<br> list.add("Fourth");<br> list.add("Fifth");
        <br> pageContext.setAttribute("list", list,
        PageContext.PAGE_SCOPE);<br>%&gt;<br><br>&lt;logic:iterate
        id="myCollectionElement" name="list"&gt;<br> Element Value: &lt;bean:write
        name="myCollectionElement" /&gt;&lt;br /&gt;<br>&lt;/logic:iterate&gt;
    </pre>
</blockquote>
</blockquote>

</body>
